はじめに

XPages アプリケーションでは、ビジネスアプリケーションのロジックはサーバーサイド Javascript （SSJS）で記述しますが、クライアントサイド Javascript （CSJS）でも利用できるさまざまな関数を提供します。それはは XSP クライアントサイド、Javascript オブジェクト関数としてまとめられています。

この記事では XSP クライアントサイド、Javascript オブジェクト関数について解説します。

 

XSP クライアントサイド、Javascript オブジェクト関数

XSP クライアントサイド Javascript オブジェクト関数では、ブラウザや XPiNC (XPages in Notes Client) での Notes で利用で呼び出せる XPages 関連の関数です。これらの関数を利用することで、XPages エンジンの提供する SSJS などのサーバーサイドの仕組みと柔軟に連携するアプリケーションを開発することができます。

また、この関数にはダイアログの表示といった汎用的な関数も含まれています。これらは一般的な Javascript の関数や、Dojo ライブラリを用いて実現することも可能です。しかし、XSP クライアントサイド Javascript オブジェクト関数で実装することで、XPages が利用できるさまざまなプラットフォームに対応させることができます。たとえば XSP.alert() 関数は、ブラウザでは Dojo のダイアログを表示しますが、Notes クライアントでは Notes のダイアログを表示します。

 

XSP クライアントサイド Javascript Object 関数

以下の表に、XPages アプリケーション開発で使用できる XSP クライアントサイド Javascript オブジェクトのパブリック関数の一覧を示します。この一覧は Lotus Domino 8.5.3 で利用できる関数です。

これらのパブリック関数のほかにプライベート関数も利用可能ですが、それらは XPages のエンジンに対して直接の操作を行う点で使用が難しく、推奨されていません。

分類/関数名	プラットフォーム	ライブラリ	説明
ダイアログ表示
XSP.alert(message) : void	All	xspClientDojo.js	ダイアログの表示
XSP.confirm(message) : boolean	All	xspClientDojo.js	「OK」または「キャンセル」を選択できる確認ダイアログの表示
XSP.error(message) : void	All	xspClientDojo.js	エラーダイアログの表示
XSP.prompt(message, defaultCaption) : string	All	xspClientDojo.js	入力ダイアログの表示
Dojo ライブラリ
XSP.djRequire(moduleName) : object	All	xspClientDojo.js	指定した Dojo モジュールのロード
送信処理
XSP.addPreSubmitListener(formId,listener,clientId,scriptId) : void	All	xspClientDojo.js	ページ送信の直前にクライアントサイドで呼ばれる JavaScript 関数の登録
XSP.addQuerySubmitListener(formId,listener,clientId,scriptId) : void	All	xspClientDojo.js	ページ送信の直前にクライアントサイドで呼ばれ、送信の続行の可否を制御する JavaScript 関数の登録
XSP.canSubmit() : boolean	All	xspClientDojo.js	ページ送信の可否を判定
XSP.allowSubmit() : void	All	xspClientDojo.js	ページ送信を可能に設定
XSP.setSubmitValue(submitValue) : void	All	xspClientDojo.js	ページ送信時に送信されるデータの設定
XSP.getSubmitValue() : object	All	xspClientDojo.js	ページ送信時に送信されるデータの取得
入力内容と妥当性確認
XSP.validateAll(formId,valmode,execId) : boolean	All	xspClientDojo.js	ページ内のすべてのクライアントサイドのコンバーターと入力妥当性判断の実行
XSP.getFieldValue(node) : : string	All	xspClientDojo.js	フィールドの値の取得
XSP.getDijitFieldValue(dj) : object	All	xspClientDojo.js	Dojo Dijit の値の取得
XSP.validateError(clientId,message) : void	All	xspClientDojo.js	入力妥当性判断の実行とエラーダイアログの表示
UI 制御
XSP.scrollWindow(x,y) : void	All	xspClientDojo.js	画面のスクロール
XSP.showSection(sectionId,show) : void	All	xspClientDojo.js	セクションの展開と省略
部分更新
XSP.partialRefreshGet(refreshId,options) : void	All	xspClientDojo.js	GET リクエストによる部分更新の実行
XSP.partialRefreshPost(refreshId,options) : void	All	xspClientDojo.js	POST リクエストによる部分更新尾の実行
イベント処理の登録
XSP.attachClientFunction(targetClientId,event,clientSideScriptName) : void	All	xspClientDojo.js	コントロールのイベントへのクライアントサイド関数の関連付け
XSP.attachClientScript(targetClientId,event,clientSideScript) : void	All	xspClientDojo.js	コントロールのイベントへのクライアントサイドスクリプトの関連付け
XSP.addOnLoad(listener) : void	All	xspClientDojo.js	ページロードイベントトへのクライアントサイドスクリプトの関連付け
UI 要素取得
XSP.findForm(nodeoe_elementId) : object	All	xspClientDojo.js	指定されたコントロールの親フォームの取得
XSP.findParentByTag(node_or_elementId) : object	All	xspClientDojo.js	指定されたコントロールの親コントロールの取得
XSP.getElementById(elementId) : object	All	xspClientDojo.js	エレメントの取得
XSP.hasDijit() : boolean	All	xspClientDojo.js	Dojo Dijit コントロールが存在するかの判断
文字列操作
XSP.trim(string) : string	All	xspClientDojo.js	文字列の前後の空白文字の取り除き
XSP.startWith(string,prefix) : string	All	xspClientDojo.js	文字列の開始文字列の判断
XSP.endWith(string.suffix) : string	All	xspClientDojo.js	文字列の終了文字列の判断
XSP.toJson(object) : string	All	xspClientDojo.js	オブジェクトの JSON への変換
XSP.fromJson(string) : object	All	xspClientDojo.js	JSON のオブジェクトへの変換
デバッグ
XSP.log(message) : void	Web/MU	xspClientDojo.js	クライアントサイドでのログの出力
XSP.dumpObject(object,option) : string	Web/MU	xspClientDebug.js	オブジェクトのダンプ情報の生成

※ プラットフォームの値は以下を示します。

• Web
• Mobile
• Notes
• CA ・・・ 複合アプリケーション (Compisite Application)
• MU ・・・ IBM Mashup Center
• All ・・・ 上記のすべて

 

関数の詳細

ダイアログ表示

XSP.alert(message) : void

ダイアログの表示

パラメータ

• message : (String)  表示するメッセージ

XSP.confirm(message) : boolean

「OK」または「キャンセル」を選択できる確認ダイアログの表示

パラメータ

• message : (String) 表示するメッセージ

戻り値

• (boolean) 「OK」を選択したときに true

XSP.error(message) : void

エラーダイアログの表示

パラメータ

• message : (string) 表示するメッセージ

XSP.prompt(message, defaultCaption) : string

入力ダイアログの表示

パラメータ

• message : (string) 表示するメッセージ
• defaultCaption : (string) 入力フィールドのデフォルト値

戻り値

(string) 設定された値

Dojo ライブラリ

 

XSP.djRequire(moduleName) : object

指定した Dojo モジュールのロード

パラメータ

moduleName : (String) ロードするモジュールのライブラリ名（例： "dijit.Dialog"）

送信処理

XSP.addPreSubmitListener(formId,listener,clientId,scriptId) : void

ページ送信の直前にクライアントサイドで呼ばれる JavaScript 関数の登録

パラメータ

• formId : 送信されるフォームの ID
• listener : 呼び出されるクライアントサイド Javascript の関数
• clientId : 同じページ内のコントロールのイベントハンドラーの ID
• scriptId : 登録するリスナーを識別する一意の名前（省略可能）

XSP.addQuerySubmitListener(formId,listener,clientId,scriptId) : void

ページ送信の直前にクライアントサイドで呼ばれ、送信の続行の可否を制御する JavaScript 関数の登録

パラメータ

• formId : 送信されるフォームの ID
• listener : 呼び出されるクライアントサイド Javascript の関数
• clientId : 同じページ内のコントロールのイベントハンドラーの ID
• scriptId : 登録するリスナーを識別する一意の名前（省略可能）

XSP.canSubmit() : boolean

ページ送信の可否を判定

戻り値

• (boolean) 送信可能であれば true

XSP.allowSubmit() : void

ページ送信を可能に設定

XSP.setSubmitValue(submitValue) : void

ページ送信時に送信されるデータの設定

パラメータ

• submitValue : (object) 送信するデータ

XSP.getSubmitValue() : object

ページ送信時に送信されるデータの取得

戻り値

• (Object) : 送信されるデータ

入力内容と妥当性確認

XSP.validateAll(formId,valmode,execId) : boolean

ページ内のすべてのクライアントサイドのコンバーターと入力妥当性判断の実行

パラメータ

• formId : (string) 検証するフォームの IDvalmode : (number) 検証するモード（0:検証なし、1:コンバータのみ実行、 2:コンバーターと妥当性検査を実行）
• execId : 同じページ内で検証を行うコントロールの ID （オプション）

XSP.getFieldValue(node) : string

stringフィールドの値の取得

XSP.getDijitFieldValue(dj) : object

Dojo Dijit の値の取得

XSP.validateError(clientId,message) : void

入力妥当性判断の実行とエラーダイアログの表示

UI 制御

XSP.scrollWindow(x,y) : void

画面のスクロール

XSP.showSection(sectionId,show) : void

セクションの展開と省略

部分更新

 

XSP.partialRefreshGet(refreshId,options) : void

GET リクエストによる部分更新の実行

XSP.partialRefreshPost(refreshId,options) : void

POST リクエストによる部分更新尾の実行

イベント処理の登録

XSP.attachClientFunction(targetClientId,event,clientSideScriptName) : void

コントロールのイベントへのクライアントサイド関数の関連付け

XSP.attachClientScript(targetClientId,event,clientSideScript) : void

コントロールのイベントへのクライアントサイドスクリプトの関連付け

XSP.addOnLoad(listener) : void

ページロードイベントトへのクライアントサイドスクリプトの関連付け

UI 要素取得

XSP.findForm(nodeoe_elementId) : object

指定されたコントロールの親フォームの取得

XSP.findParentByTag(node_or_elementId) : object

指定されたコントロールの親コントロールの取得

XSP.getElementById(elementId) : object

エレメントの取得

XSP.hasDijit() : boolean

Dojo Dijit コントロールが存在するかの判断

文字列操作

 

XSP.trim(string) : string

文字列の前後の空白文字の取り除き

XSP.startWith(string,prefix) : string

文字列の開始文字列の判断

XSP.endWith(string.suffix) : string

文字列の終了文字列の判断

XSP.toJson(object) : string

オブジェクトの JSON への変換

XSP.fromJson(string) : object

JSON のオブジェクトへの変換

デバッグ

XSP.log(message) : void

Web/MUクライアントサイドでのログの出力

XSP.dumpObject(object,option) : string

Web/MUxspClientDebug.jsオブジェクトのダンプ情報の生成

ダイアログ表示

XSP.alert(message) : void

ダイアログの表示

パラメータ

message : (String)  表示するメッセージ

XSP.confirm(message) : boolean

「OK」または「キャンセル」を選択できる確認ダイアログの表示

パラメータ

message : (String) 表示するメッセージ

戻り値

• (boolean) 「OK」を選択したときに true

XSP.error(message) : void

エラーダイアログの表示

パラメータ

• message : (string) 表示するメッセージ

XSP.prompt(message, defaultCaption) : string

入力ダイアログの表示

パラメータ

• message : (string) 表示するメッセージ
• defaultCaption : (string) 入力フィールドのデフォルト値

戻り値

• (string) 設定された値

Dojo ライブラリ

XSP.djRequire(moduleName) : object

指定した Dojo モジュールのロード

パラメータ

• moduleName : (String) ロードするモジュールのライブラリ名（例： "dijit.Dialog"）

送信処理

XSP.addPreSubmitListener(formId,listener,clientId,scriptId) : void

ページ送信の直前にクライアントサイドで呼ばれる JavaScript 関数の登録

パラメータ

• formId : 送信されるフォームの ID
• listener : 呼び出されるクライアントサイド Javascript の関数
• clientId : 同じページ内のコントロールのイベントハンドラーの ID
• scriptId : 登録するリスナーを識別する一意の名前（省略可能）

XSP.addQuerySubmitListener(formId,listener,clientId,scriptId) : void

ページ送信の直前にクライアントサイドで呼ばれ、送信の続行の可否を制御する JavaScript 関数の登録

パラメータ

• formId : 送信されるフォームの ID
• listener : 呼び出されるクライアントサイド Javascript の関数
• clientId : 同じページ内のコントロールのイベントハンドラーの ID
• scriptId : 登録するリスナーを識別する一意の名前（省略可能）

XSP.canSubmit() : boolean

ページ送信の可否を判定

戻り値

• (boolean) 送信可能であれば true

XSP.allowSubmit() : void

ページ送信を可能に設定

XSP.setSubmitValue(submitValue) : void

ページ送信時に送信されるデータの設定

パラメータ

submitValue : (object) 送信するデータ

XSP.getSubmitValue() : object

ページ送信時に送信されるデータの取得

戻り値

• (object) : 送信されるデータ

入力内容と妥当性確認

XSP.validateAll(formId,valmode,execId) : boolean

ページ内のすべてのクライアントサイドのコンバーターと入力妥当性判断の実行

パラメータ

• formId : (string) 検証するフォームの ID
• valmode : (number) 検証するモード（0:検証なし、1:コンバータのみ実行、 2:コンバーターと妥当性検査を実行）
• execId : 同じページ内で検証を行うコントロールの ID （オプション）

XSP.getFieldValue(node) : string

stringフィールドの値の取得

XSP.getDijitFieldValue(dj) : object

Dojo Dijit の値の取得

XSP.validateError(clientId,message) : void

入力妥当性判断の実行とエラーダイアログの表示

UI 制御

XSP.scrollWindow(x,y) : void

画面のスクロール

XSP.showSection(sectionId,show) : void

セクションの展開と省略

部分更新

 

XSP.partialRefreshGet(refreshId,options) : void

GET リクエストによる部分更新の実行

XSP.partialRefreshPost(refreshId,options) : void

POST リクエストによる部分更新尾の実行

イベント処理の登録

XSP.attachClientFunction(targetClientId,event,clientSideScriptName) : void

コントロールのイベントへのクライアントサイド関数の関連付け

XSP.attachClientScript(targetClientId,event,clientSideScript) : void

コントロールのイベントへのクライアントサイドスクリプトの関連付け

XSP.addOnLoad(listener) : void

ページロードイベントトへのクライアントサイドスクリプトの関連付け

UI 要素取得

XSP.findForm(nodeoe_elementId) : object

指定されたコントロールの親フォームの取得

XSP.findParentByTag(node_or_elementId) : object

指定されたコントロールの親コントロールの取得

XSP.getElementById(elementId) : object

エレメントの取得

XSP.hasDijit() : boolean

Dojo Dijit コントロールが存在するかの判断

文字列操作

 

XSP.trim(string) : string

文字列の前後の空白文字の取り除き

XSP.startWith(string,prefix) : string

文字列の開始文字列の判断

XSP.endWith(string.suffix) : string

文字列の終了文字列の判断

XSP.toJson(object) : string

オブジェクトの JSON への変換

XSP.fromJson(string) : object

デバッグ

XSP.log(message) : void

Web/MUクライアントサイドでのログの出力

XSP.dumpObject(object,option) : string

 

参考文献

XSP クライアントサイド Javascript オブジェクト関数についての詳細は 「XPages Portable Command Guide」 の第４章に記載されています。

 

サンプルコード

XSP クライアントサイド Javascript オブジェクト関数を実装したサンプルアプリケーションを以下に公開しています。

XspCSJSO.zip